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Technical Documentation 


ArgAsm is the generic name for our suite of Editor/Assembler development tools. 
We supply two versions in the package; named ArgEd and Arg respectively. The 
former ("ArgEd") contains an interactive Editor/Assembler in one program with 
an Intuition Front-end (pulldown menu’s etc), while the latter ("Arg") is a 
standalone version of the Assembler capable of executing from the CLI or from 
within a Batch file. Both versions contain exactly the same Assembler program. 
If possible, try to learn and use our own Editor, as it will greatly increase your 
Assembly Development performance, by avoiding unnecessary disk saving and 
reloading of sourcefiles. Also, our Editor is one of the fastest and most flexible 
around, especially at scrolling and page update speeds but it also has multi-file 
and multi-window capabilities; which is a worthwhile consideration when 
deciding which editor to use. 


Some parts of this manual may relate specifically to ArgEd (the integrated 
editor/assembler) or Arg (the standalone file assembler). 


The ArgAsm package comprises: 
2 disks and a 70 page manual in an AS pvc binder with reply card. 


System requirements: 


Commodore Amiga computer with a minimum of Imb of RAM, a single disk 
drive, monitor, keyboard and mouse (see page 3 for further details). 


Copyright (c)1989 Argonaut Software Limited. 


Printing History. 
1st Edition, October 1989. 


Written by Jez San during 1989 and completed on the 10th October. 


Word Processed on MS Word and Word Perfect. Typeset on Ventura v2.0. 
Computer System: a Imb 20mhz 386 AT with 64K cache & Vega VGA fastwrite. 
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Introduction. 


ArgAsm Serial Number: ne: ee 


Minimum System Requirements. 


ArgAsm is supplied to operate on a Commodore Amiga computer. It has been 
tested on a variety of configurations including the 1.2, 1.3 and 1.4 OS’s. It is known 
to be compatible with the entire Motorola 680x0 range, and has been tested on 
the 68000, 68010, 68020 and 68030 processors, and will probably work on the 68040 
which was not available at the time of writing this manual. 


The minimum memory requirement for ArgAsm to run in any useful manner is 
about 1 megabyte of free ram, but for large projects we recommend 1.5 meg or 
more. We have been able to assemble quite substantial programs (eg: a Flight 
Simulator, 800k of object code) with only 1.5 meg of memory inhouse at Argonaut. 
As with most multi-tasking machines, more RAM is always a useful addition to 
your computer, as is a nice fast hard disk. 


ArgAsm supports all standard AmigaDOS devices, including RAM-Disks, Hard 
Disks, Networks, etc. We have streamlined ArgAsm to assemble as quickly as 
possible once the sourcefile has been read into the computer. But our bottleneck 
is still disk I/O performance since the Assembler can outrun most hard disks. We 
therefore recommend you to go for the fastest hard disk your budget can support. 
The faster your disk performance, the faster ArgAsm can read, and then assemble 
your sourcefiles. As proof, do some assemblies from Ram-disk just to see how 
ArgAsm performs in an ideal I/O situation. 
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Technical Issues. 


ArgAsm is a One-Pass assembler. This means that it only needs to read and parse 
the source file once in order to create the correct object code. Most assemblers 
on the Amiga are Two-Pass, though some of them only read the source file once 
(but still parse twice) to cut down on I/O time. In real terms, there is no loss of 
functionality between a well written one-pass assembler and a two pass assembler, 
but there are obvious performance gains in the former! The concept isn’t new, as 
many compilers are One-Pass, including a few recent PASCAL and MODULA-2 
implementations. 


A two-pass assembler (like Assem, Devpac and Cape) will simply assemble the 
source code twice, the first time ignoring any ’undefined symbol’ errors due to 
forward references and the second time around, with full error reporting writing 
out the correct object code. A one-pass assembler (like ArgAsm) simply 
assembles the source code directly into an object code buffer, keeping track of 
any forward references as it goes along. After the pass is complete, any forward 
references are resolved and inserted into the object code buffer to create the 
correct code exactly as if it had been done in two-passes, when in reality it was 
about ’one and a bit’ passes. The advantage of this is naturally a doubling in 
performance over conventional assembly techniques, the disadvantage is that the 
object code buffer must be held in memory at all times. In real terms there is little 
loss of memory since most two-pass assemblers buffer up their object code to 
speed up on disk I/O, thus taking up the same memory as ArgAsm uses. In some 
ways, being a one-pass assembler can be more memory efficient than a two-pass 
one that buffers up the sourcefiles, because once it has parsed a sourcefile, it 
doesn’t need to be held in memory for the next pass (since there isn’t onc), which 
is great when you have lots of Include files at the same nest level. 


When an Assembly Listing File has been requested, ArgAsm produces this in the 
same pass as the Assembly is being performed. For most instructions, there will 
be no difference between our Listings, and those generated by other Assemblers. 
But, if there were any forward references in the sourcecode then the listing will 
show zeroes in the hexbyte column of the listing output file. This does not affect 
the object code generation in any way, and is purely a Listing idiosyncracy due to 
the one-pass nature of Assembly. Most people don’t even bother reading the 
actual hex bytes in an Assembly Listing anyway, especially when we went to the 
trouble of cramming in a lot of extra 68000 information in our listing files that 
other assemblers cannot produce. 
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Technical Support. 


Weare only too willing to offer help and advice with any problems you might have 
when using ArgAsm, but this must be limited to direct use of ArgAsm. We are 
unable to offer general programming advice or help you track down bugs in your 
code, but we will directly support ArgAsm and its usage on the Amiga computer. 
Simply write in or FAX us with a concise description of the problem and we will 
get back to you as soon as we can (usually within 48 hours). Leave us your name, 
(rank?) and serial number and also an address/telephone number where you can 
be reached. Ifthe problem is really urgent and you need to speak to someone by 
’phone, then our preferred time to call the ArgAsm Tech Support is between 2 
and 3pm UK time (9-10am Eastern USA time). If you call us at any other time, 
we cannot guarantee that the appropriate person will be there. 


ArgAsm has been in development for a year, and we won’t stop here! We intend 
to improve, perfect, incorporate ideas and fix any new bugs to keep ArgAsm on 
top! No product can be guaranteed ’Bug Free.’ As with any product of this 
complexity (ArgAsm is over 100k of pure handcrafted machine code, 1 meg of 
source code) there are always bound to be subtle things we didn’t find, even during 
our extensive testing on both sides of the Atlantic. If you have discovered a bug 
or compatibility issue then we need your help to track it down so that we can fix 
it for the next release. Try to narrow any problem down to a few lines of example 
code that consistently show up the existence of the bug every time. If you can send 
it to us on disk, or if its easier by FAX then we will get right onto it! If we can 
Reproduce it, we can fix it. And we WILL fix it! As an extra incentive, The first 
person to highlight an undiscovered bug will receive an upgrade at our expense. 
If you find you have to alter your sourcecode to skirt around a problem or 
idiosyncrasy, don’t just keep it to yourself. Tell us, and with any luck the next 
upgrade release will have your improvement requests made to it. 


You must be registered with us prior to using our Tech Support service, and you 


will need to supply your Serial Number with any Enquiry, be it by mail, fax or 
*phone. 


ArgAsm Page 5 


Upgrade Policy. 


From time to time, we will make available Enhancement Upgrades to add 
features, increase the functionality or to fix bugs/idiosyncracies in ArgAsm that 
are reported by our customers. The fee for an Upgrade will be small and is only 
there to cover costs in getting it to you. In general, A Bugfix Upgrade will cost 
less than a Feature Enhancement upgrade: due to less paperwork (manuals, 
programming etc). Approximate cost will be around £10 to £15 pounds sterling. 


In addition to normal upgrades to ArgAsm, we intend to have a more powerful 
big brother that is provisionally known as ArgAsm Professional (not that we’re 
implying the current version isn’t professional) that will support the extra 68030 
specific instructions (and maybe even 68040), 68881/68882 and many other 
sophisticated enhancements like a built-in fast linker, not yet seen in an Amiga 
Assembler. This package will cost more than the original ArgAsm package and 
will be marketed on a two-tier sophistication level. We will of course allow 
upgrades from ArgAsm to ArgAsm Pro, for a reasonable fee that has yet to be 
decided, but our policy is to provide existing users with a way of upgrading to the 
latest and greatest products we sell. Our Existing users will never be penalised 
when we add to, or improve our product range. 


As with any usage of ArgAsm, we urge all customers to Register with us so we 
can provide notice of improvements, bug fixes or new products. Needless to say, 
Upgrades will only be available to registered users. 


Piracy and Software Theft. 


As a small company, we suffer greatly from people giving copies of our products 
to their friends, or uploading versions onto bulletin boards. Please don’t! To 
bring a product of this quality and functionality to market is very expensive indeed. 
From Development, to Production to Marketing, it has been expensive 
achievement. Any loss in our sales or earnings prevents us from recouping the 
huge costs involved and makes it impossible for us to improve and support this or 
any other product. If you want to allow us to continue to create products as good 
as ArgAsm, then please, do NOT give any copies of this product to your friends, 
colleagues or co-developers. If they want a copy, tell them nicely to buy one. We 
cannot afford any piracy to take place. Please, help us fight this crime. We all get 
hurt; The small software companies who have no ’bottomless pit’ backing, just 
income from the products they sell. 


Copying ArgAsm for any reason other than personal backup to protect against 


loss is contravening the Copyright Law of England, and will be dealt with 
accordingly. 
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Additional copies of ArgAsm. 


If you want to purchase further copies of ArgAsm, we can accomodate. Also, Site 
ana Network licenses are available at attractive rates available upon request. 


We all hope you enjoy using ArgAsm and that it gives you assistance in creating 
excellent assembler programs. 


Thank you. 
Jez San (Director) and the good programming folk at Argonaut Software Ltd. 


This product was created over a period of a year by: Jez San, James Hakewill, 
Philip Pratt, and Jon Wolff with a great deal of help from everyone at Argonaut 
for suggestions, ideas and requirements. We would like to thank all of our very 
helpful alpha and beta testers, without whom this product would have taken a lot 
longer to write. In particular the UK testers were: Sam Littlewood, Spencer 
Shanson, Paul Ockendon, David Parkinson, Matt Adams and in the USA: Bill 
Hawes, Adam Levin, Mike Sinz, Charlie Heath, Chris Green, Glen McDermiad.. 
and a lot of good folks on BIX and CIX. 


Our Address. 


Argonaut Software Limited, 
ArgAsm Tech Support. 

7 Millway, Mill Hill, 
London NW7 3QR. 
ENGLAND. 


The phone number is (01) 906 3744, and the fax number is (01) 959 5052. 
International callers, please dial your International Sequence (eg: USA folk 
usually dial 011) and then + 44 1 906 3744. ie: England is country code + 44 and 
the London city code is +1. 

On May 1° 1990, British Telecom will alter the London dialling code from 1 to 


81 so if you get a recorded anouncement on the normal phone numbers, give the 
new dialling code a try. 


You can also contact us on CIX in the UK, and BIX in the USA. Our ID is "jsan". 
Look out for announcements of our support conferences on these services. 


CIX is on (01) 399 5252 for 2400 baud, and (01) 390 1255 for 9600 baud Courier 
HST. 
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Extra Development tools. 


An invaluable extra development tool is a Debugger. We don’t supply one with 
ArgAsm just yet, for many reasons, the most important being that we only like to 
do products where we know we can be the best at what we do. That usually means 
being faster, or better. To be honest, we don’t think we could do any better a 
debugger than is already available elsewhere so there is unlikely to be one from 
Argonaut unless of course someone submits one to us that fulfills our high 
requirements. We have used many Amiga debuggers over the years, and two 
spring to mind that are really quite good. The first is MonAm2 from Hisoft, it is 
very powerful, eminently usable, and is good for low level work. An excellent all 
round Monitor, but at the time of printing it was not available separately. Hisoft 
tell us that they are planning on marketing it separately so do check with them 
about it. Another good debugger is MetaScope from MetaDigm. This is a much 
friendlier monitor than MonAm?, but doesn’t seem so usable for low level work. 
Also, it runs on a Workbench screen so suffers more from buggy programs 
interfering with it than MonAm?, which creates its own screen. This one definitely 
is available as a standalone product. The last two debuggers are available free 
with C compilers, these are CodeProbe (CPR) from Lattice, and SDB from Manx. 
Both are excellent source level debuggers, but don’t seem to be available as 
standalone packages just yet. You can always ask, though. 


Perhaps by the time ArgAsm Professional is ready, we may have changed our 
mind and written our own Amiga Debugger. Watch this space, and let us know 
if yet another debugger is really wanted? We intend to write a fast multi-format 
linker, possibly built into the assembler. 


Arp.Library 


ArgEd uses the infamous Arp.Library file requester written by Charlie Heath of 
MicroSmiths. If Arp.Library isn’t present in your libs: directory you will only see 
a simple file requester (a String Gadget) when trying to load or save files. 


The Arp file requester has a scrolling list of files that you can double-click to select 
the one you want. It also has gadgets to scroll up and down, or to change the 
device. You can also type the filename in directly, or use the last selected one by 
pressing Return or clicking on OK. 
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Distribution Disk contents. 


Two disks are supplied with this package. The ArgAsm disk contains a slightly 
stripped down 1.3.2 Workbench, together with Arg, ArgEd and Blink in the C: 
directory. The other disk contains the 1.3 Include files that are referenced by the 
Amiga programming books and are used if you want to write nice OS friendly 
programs. Also we provided some example programs complete with sourcecode 
to get you going. The free upgrade disk you will receive when you register with 
us will contain new versions of Arg and ArgEd with added features and any 
reported bugs fixed. It will also contain the latest Include files, which we 
anticipate being 1.4 and ECS compatible. It will also contain extra examples and 
sample programs. 


"Outside a dog, man’s best friend is a book. Inside a dog, its too dark to read!" 
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Executing ArgEd from the CLI 


The simplest way of running the combined Editor/Assembler version of ArgAsm 
is to type ArgEd from the CLI. This will load up with a blank page, ready for you 
to either type away or load something you were working on earlier (with the Load 
menu). You may alternatively specify any number of filenames which ArgEd will 
load into different windows ready for you to do a mammoth editing session. 


eg: 


1> ArgEd 
1>  ArgEd DHO:Frog 
1> ArgEd Allsyms.i frog.s types.i 


If you were working on something earlier and had done a Snapshot, you simply 
type ArgEd to continue working where you left off. 


Executing Arg from the CLI 


To run the standalone file-based Assembler is not quite so straightforward as 
there are a myriad of CLI options, none of which are very memorable so take the 
time to study them here. The golden rule is that we have tried to make ArgAsm 
as compatible as possible with the standard Commodore Assemblers. We have 
largely followed the Metacomco ASSEM standard for Command Line 
parameters, whilst maintaining as much compatibility as possible with Cape and 
Devpac. 


The CLI format is : 
1> Arg <sourcefile> (-Option -Option) 
Eg: To simply Assemble a file with no output file or frills, type: 


1> Arg sourcefile.s 


Naturally, this won’t save any object code output, produce a listing, or in any way 
serve a useful purpose other than proving that ArgAsm actually assembled your 
file. This is usually done to check for errors, or even just to boast to your friends 
how fast ArgAsm is! 
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A Summary of Arg CLI options 


-a Accept a source file (for Cape compatibility only) 

-b Disables all object code file generation. 

-e Error list printout at the end of the listing. 

-h Specify a header file to be Included before your first file is assembled. 


(This is the same as "Include Filename" at the start of your source code) 
-i Include directory pathlist. 
(like the INCDIR directive) 
-] Specify an assembly listing filename (defaults to the console) 
-m Allows you to specify the size (in bytes) for the Object Code Buffer. 
(the default is 64000 but you can specify different amounts.) 


-0 Specify an object code filename. 
(No object file will be generated if you don’t ask for one!) 
-p Disables Printer Control characters from error reports. 
(in case they confuse your printer or redirected output file). 
-q Quiet flag, avoids printing anything (for those peaceful days) 
-S Symbol table printout at the end of the listing. 
(Output in the form of EQUs, ready for later re-assembly if required) 
-t display timing and assembly statistics. 
(Useful assembly information and timings). 
-u Uppercase all symbols (same as OPT C-, makes them case insensitive) 
-w Turns Warning errors off (same as OPT W-) 
“x Makes code executeable (same as OPT L-) 


ArgAsm supports the standard AmigaDOS output redirection so you can obtain 
printouts or files of your ArgAsm sessions. 


eg: 
1> Arg frog.s -o frog.o 

This is the usual form an Assembly will take. It simply assembles the specified 
source file "frog.s" into an object code file "frog.o". Note, for even lazier typists 
you can have an OUTPUT directive at the start of your source code to specify 
the default object filename and then you won’t even have to have it present in the 


CLI options, as ArgAsm will use the first one given. 


Let’s be more ambitious... 
1> Arg >wdog-.s -o dog -I list.Ist -i Include: -t 
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The above will assembly the source file "dog.s", getting any include files from 
either the current directory or the "Include:" assigned directory. The object code 
output will be written to "dog" and an assembly listing will be written to "list.Ist". 
Also, ArgAsm will display the timings and statics when its finished. And just for 
history purposes, we have captured the session log into a file "w'. 


Object Code Buffer 


If you are assembling programs, you may see fata error messages claiming that 
the object code buffer is full. This isn’t drastic as the object buffer can be set in 
advance to ant size you want (provided you have enough memory, of course). 
ArgAsm needs to store the entire object code in memory in its object code buffer. 
This has to be allocated in advance of the assembly because it must be contiguous. 
The default object buffer is 64K (65536 bytes), but as you begin to write bigger 
and bigger programs, you will need to adjust this value. It can be adjusted with 
the -m CLI option or from within ArgEd’s Assembly Options page. 


Memory Problems 


ArgAsm is more sensitive to low memory situations than other assemblers. It has 
been optimised to assemble source code quickly and not hang about worrying how 
to conserve memory. Quite different from running out of object code buffer 
space, you may receive an error claiming that you are fatally out of memory. This 
error is more serious, as you will have to either buy more RAM for your Amiga, 
or prune down your source and object code in size to fit your Amiga’s RAM. This 
can usually be acheived by minimising the amount of object code bufferspace 
(with -m) and also splitting up your source files into finer chunks and utilising 
Include to read them in piecemeal fashion. That way, ArgAsm can allocate 
smaller chunks of memory and use it more effectively. 


ArgAsm Instruction Set 


There isn’t space to list the various 68000 instructions that ArgAsm supports. All 
Motorola documented 68000 instructions and addressing modes are supported, 
in a compatible way to Metacomco’s ASSEM, and Hisoft’s Devpac 2. We also 
support the extensions to the Motorola standard like zero offsets on (PC,Xn) and 
(An,Xn) addressing modes. 


We recommend purchasing Motorola’s fine 68000 technical reference manual. 
[The 68000 bible, accept no substitutes] 
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ArgEd, the Editor. 


You may have read elsewhere that ArgAsm is supplied in two forms, the first is a 
standalone assembler that will accept source files from disk. These may have been 
produced with your preferred editor that you may already know and love, or 
possibly the source code may already exist, for instance Commodore supplied 
examples. The second version of ArgAsm supplied contains both a screen editor 
and a built-in Assembler, collectively called ArgEd. This allows you to 
interactively edit your source code, assemble, then edit again to fix any errors. All 
this is done without any unnecessary disk activity which allows greater productivity 
and flexibility on the part of the programmer. 


ArgEd is a RAM-based multi-window screen editor. 


"RAM-based" means that the entire contents of the files that you edit must 
comfortably fit into your available RAM. In the unlikely event that you want to 
edit files larger than your available RAM you must either split your file into 
smaller chunks (quite how you do this is a difficult exercise on its own!), and edit 
these separately, or alternatively you can purchase a fully fledged virtual-file 
editor, which is designed to perform such functions. In most cases the files you 
edit will be smaller than your free RAM, simply because most Amiga’s have at 
least 1 meg of RAM, and most assembler source codes are much smaller than 1 
meg. Most are around 50 to 100k, and the ideal maximum size for a source file is 
in fact only a few hundred kilobytes. If you are constantly running out of memory 
when editing files, we suggest you seriously think about purchasing more RAM. 
After all, RAM is cheap, useful and very cost effective! 


"multi-window" means that you can have many windows open at the same time. 
This is an unusual feature, as most editor’s aren’t smart enough to do this well 
enough to be usable. These windows can be looking at the same file in different 
places, or you can open up lots of different files all in their own separate window. 
Yet again, all the files that you open must be able to fit in RAM at the same time. 


"screen editor" means that the editor displays an entire screenful of text in a 
window and allows you to move a cursor about whilst scrolling the text back and 
forth, left and right to allow you to edit your text anywhere on the window. This 
is more advanced than earlier "line editors" where you can only edit the current 
line, and moving back and forth was cumbersome and rather unfriendly. In 
particular, ArgEd has been programmed with performance in mind, so that you 
can page or scroll the windows back and forth instantly without waiting for the 
editor to catch up or the text to be redrawn like with earlier Amiga editors. 
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An Example Edit Session. 


Okay, let’s just briefly go through a way to get you up and running. 


Torun ArgEd you simply type ArgEd at the CLI prompt. Assuming that you are 
running it for the first time (and were not in the middle of something last time you 
used it) ArgEd will put up a blank page ready for you to type away. 


The cursor will be visible at the start of the page, and whatever text you type will 
be inserted at that point. Hit RETURN at the end of each line. If you make any 
mistakes you can delete the previous character with the BACKSPACE key, or 
you can delete the character under the cursor with the DELETE key. 


You move the cursor about with the arrow keys. You can only move up or down 
if you have text there, so you cannot scroll away and lose your text. When you get 
near the top or bottom of the window, the text window will be scrolled to reveal 
another line in the direction you moved. If you wish to jump a whole page at a 
time, hold down the SHIFT key as you hit the arrow keys. Also, you can move to 
the beginning and end of the line with CONTROL held down and pressing the 
Left and Right arrows. You can get to the Top and Bottom of your document by 
holding down CONTROL and pressing the Up and Down arrows. You can also 
get to the Top and Bottom of your document by pressing A miga-T and Amiga-B 
respectively. 


Now go ahead and type in some example text, and play with deleting and inserting 
lines and generally getting comfortable with scrolling and paging windows about. 


<Some time passes whilst you experiment with ArgEd > 


Having typed in your source code you will then want to save it to disk. So press 
Amiga-S and a requester will pop up asking for the name you want to call it. You 
can either click on a filename you want to overwrite, or type in a new name for it. 
A good convention for source code filenames is to end them with a .S, eg: 
MYFILE.S or SOURCE_CODES, this is so that you can always know its an 
assembly source code file. Some people prefer .ASM instead. 


To load in source code text that you have previously saved, press Amiga-L to get 
the file requester, and then specify which filename you want. It will be loaded in 
the current window replacing any previous contents. If you wish to insert a file 
from disk into the current contents of a window, you press Amiga-I instead. This 
will insert the text as if you had typed it into that spot. 
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ArgEd’s Menubar 


As with all Intuition compatible programs on the Amiga, pressing the right mouse 
button will invoke the menu bar at the top of the screen. This contains a menu of 
categories which you can move the mouse pointer over to bring down a sub-menu 
list over which you can move the mouse pointer. You simply release the mouse 
button while the pointer is on your selected menu choice for it to take effect. If 
you wanted a different menu you can move the mouse around while still holding 
down the button. If nothing takes your fancy simply release the mouse button 
when the pointer isn’t on a menu. This has the effect of cancelling your menu 
request. 


ArgEd has the following menu categories. 


PROJECT, WINDOWS, SEARCH, GOTO, ARGASM, BLOCKS, SPECIAL 


Taking these in turn, the menu categories are listed in order together with their 
sub-menus. Any keyboard shortcuts are listed in brackets next to the sub-menu 
name. 
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The PROJECT Menu 


These functions are generally to do with the current project, for instance loading, 
and saving files or quitting. 


Clear (A miga-C) will wipe out all text in the current window ready for you to start 
afresh. If you hadn’t previously saved the text, you will be given a last chance to 
back out by saying whether it is okay to continue or cancel the request to Clear. 


Load (Amiga-L) is to load a new source file from disk into the current window. 
Yet again, if there was unsaved text still in the window you will be asked if 
everything is still okay to continue. A file requester will pop up and you can select 
the file by clicking on it with the mouse, or typing a filename (and directory) into 
the string-gadgets at the bottom. The file requester is part of the "Arp.library" 
package, and if for some reason this isn’t on your system disk the nice file requester 
will be replaced with a simple string requester asking for the filename with no 
frills or gloss. 


Save (shift-A miga-S) will save the text of the current window as the same name 
as was last used. If this is the first time the file has been saved, then you will be 
requested for a filename. 


Save as (Amiga-S) will first request a filename, and then save the text of the 
current window to disk. This is usually done the first time you save a file, or if you 
want to save it under a new name for backup purposes etc. If you are happy with 
the present filename you may as well use save instead of Save as. 


Insert File (Amiga-I) will insert a file from disk at the current cursor position as 
if you had typed it in directly. The inserted text will become part of the current 
file when you save it out. The original file on the disk that was inserted will be left 
untouched on the disk. 


Quit (A miga-Q) will quit from the current window, closing it up and deallocating 
any memory that it was using. If the file had not been recently saved you will be 
asked if it is okay to proceed. If this was the only ArgEd window that was open, 
the program will then quit and return to AmigaDOS. If more than one ArgEd 
window was open, Intuition (the Amiga OS) will select another window to be 
active. This may not be an ArgEd one, so be sure to check where the new activated 
window is, and if you don’t agree, click on the one you want. 


Quit All is a quick way of quitting the program, as it effectively does a quit of all 


ArgEd windows. This menu option doesn’t have a keyboard shortcut as it’s too 
easy to lose your files accidently. 
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The WINDOWS Menu 


Open New Window (Amiga-W) will create a new blank window ready for you to 
type in some new source code text. The window will not be related to the last file 
you were editing (see the Split Vert and Split Horiz subcategories for that). The 
main use of this is to type or load in a new file into a new window so that you can 
edit more than one file at the same time. Quite often you will only be editing one 
file, but referring to a few others, and by opening up a window for each you can 
scroll around looking for the information you want. Also, you can use ArgEd’s 
powerful searching facilities to track down labels or references you are interested 
In, 


Close Active Window (Amiga-K) will close down the currently active window. 
This is the same as hitting the Close gadget with the mouse pointer in the top left 
corner of the window. Usually you would want to close down a window (as 
opposed to Quitting) if it was a split view of a file that another window was 
dis)laying. 


Split Horizontally (A miga-X) is used to give you a another view of the same file. 
The current window will shrink to half its size, being replaced by another similar 
window on the right side of it. Once split, windows can scroll independantly 
allowing you to look or make changes at different places in the same file. Note 
that changes in one window that affect another will be displayed as they occur. 
You can split a window quite a few times before it becomes too small to use (at 
which point ArgEd will keep it from getting any smaller but will still let you split 
into more windows). After a few splits it becomes pointless splitting any further 
(diminishing returns) and at some point the Amiga OS will become sluggish having 
to update and clip the text to all these windows. So keep to a sensible maximum 
number of windows onscreen at any one time (about 5 or 6). 


Split Vertically (Amiga Y) is as above, only it splits the windows so that they are 
halved vertically and the two new windows are on top of each other. 


Window Fullsize (Amiga-E) will expand the current window to fill the screen. 
This is usually done when you have a few windows on the screen and decide you 
want to see maximum detail in one particular window. Hitting Amiga-E is a quick 
way of getting a window as large as possible and has the same effect as dragging 
the window with the mouse to the top left of the screen, then grabbing the sizing 
gadget and stretching until the window is at fullsize. The opposite is Shrink 
Window. 
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Shrink Window (Amiga-U) will unsize a window and make it as small as possible. 
Used when you want to tidy up your editing screen and keep windows from 
cluttering up your work. When you want to go back to the file you can click to 
activate it then do a Window Fullsize (Amiga E) to bring it back to popularity 
again. 


Activate Next Window (Amiga-D) will cycle through activating a different split 


window of the same file each time it is selected. It is the same as you clicking in 
a different window each time. 
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The SEARCH Menu 


Find (Amiga-F) will pop up a requester asking for some text that you wish to 
search for. The search will start from the cursor position and will stop at the end 
of the file. If found, the cursor will jump to the start of the text you were searching 
for, if necessary repositioning the window so that the text is visible onscreen. At 
this point, you may want to replace the text with something else (by selecting 
Replace, Amiga-R) or you could find the next occurence (by selecting Find Next, 
Amiga-N). The Find requester allows you to enter the text you want to search 
for in a string gadget, and also to select whether you want the search to be case 
insensitive (ignoring the difference between capitals and lower case), and also 
allows you to specify a replace string to be used if necessary. Also, you can select 
to Search backwards for the previous occurence. 


Find Next (Amiga-N) will continue the search for your specified text string and 
display the next occurence if one was found. It has the same function as selecting 
Find again with the same settings. 


Find Previous (A miga-P) will continue the search for your text string entered with 
Find but will go backwards through your file to find the previous occurrence 
rather than the Next. 


Find Label (Amiga-M) is an unusual but powerful function to find the original 
label definition (be it an Equate, Subroutine or Table start) of something the 
cursor is on. If your cursor was on a subroutine call to a specified label, you would 
click on that label with the mouse (or move the cursor there) and select Find 
Label. ArgEd will enter the current label as a search string but will only look for 
it at the start of a line, which could only be a label definition. 


Global Replace (Amiga-@) will start at the current cursor position, and will 
replace every occurrence of the search string with the replace text string. 
Although it is much faster than doing it by hand, it can sometimes take time 
(several seconds) on a big file, so be patient. 
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| The GOTO Menu 


Top (Amiga-T) will instantly redraw the window at the very top of the file and will 
place the cursor at the top of the window. 


Bottom (Amiga-B) will instantly redraw the window at the very bottom of the file, 
and will place the cursor at the end of the window. 


Line (Amiga-G) will pop-up a requester asking which line you want to go to. It 
will then put that line in the centre of the window, with the cursor on top of the 
first character of your line. This is mainly used to visit lines given to you from 
error reports. 


Block (Amiga-O) will go to the start of your block definition (as defined by the 
block marker keys F1 and F2 respectively). 
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This menu category is only for assembling the source code in the currently selected 
window. 


Assemble (Amiga-A) will pop-up a large requester full of assembly options. To 
avoid the Assembly Options requester, and go straight into the assembler, hold 
down Shift while pressing Amiga-A. 


Assembly Options 


The Assemble-Options requester will pop up with a number of gadgets for you 
to select what options you want when assembling your source code. An 
explanation of each option follows : 


The Object Code Type can be either Executeable or Linkable. Executeable code 
must have no XREF or XDEF references to other modules, since it will become 
arunnable standalone file. Linkable code can have XREF/XDEFS referencing 
other object code modules that will be resolved during linking. 


Case Dependance: refers to whether upper and lower case labels are treated as 
different or the same. Case Dependance will treat Frog’ as different to ’frog’. 
Case Independance will uppercase all labels before processing so that upper and 
lower case differences are ignored and ’Frog’ is the same as ’frog’ or FROG?’ since 
they all become upper case. 


Debug Info: refers to whether symbols are included in the output file. You will 
normally want it set to NONE for shippable code (to stop other people seeing 
your secrets), but for development purposes you would usually have Normal 
debugging info. That way, the Monitor program will be able to show your symbols 
as an assistance to debugging. 


List To: refers to where the listing file will be sent. If you select None, then no 
listing file will be created. This is the fastest way of using the assembler. If you 
select Screen then listing will be sent to the console "*" or selecting Printer would 
send the file to "PRT:". You may also send the file to a named disk file for later 
examination or printing. 


Output To: allows you to specify where the object code file is sent. You would 
normally just leave this option set on DISK, and have an OUTPUT directive in 
your source file. Alternatively, leave it set on NONE and no object code will be 
generated. You can fix assembly errors more quickly by repetitive assembly, then 
editing without writing the object code to disk. 
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Error Options: allows you to disable Warning Error messages. Most warnings 
can be ignored if you know what you are doing. Similarly, Optimisation warnings 
will usually want to be ignored. 


List Options: refers to your various choices of listing information. Select Macros 
if you want Macros to be expanded in the listing or leave it unselected if you just 
want to see the macrocalls. This is the same as OPT M +. Similarly with Include 
files, select it if you want to see them listed. The Narrowlist option will make an 
attempt at shrinking the width of the listing by leaving out columns and truncating 
lines. The Timings option allows you to have an extra column of the 68000 
instruction cycle times, together with read/write cycles and the Flags that are 
affected by each instruction. This is very useful and makes interesting reading. It 
allows you to optimise your code by paying careful consideration to how quick 
each instruction is. You would normally have to have a reference book by your 
side looking up each instruction manually. Finally, selecting the Error option will 
print a list of errors at the end of assembly, normally the errors would be printed 
up as they occur. 


The Maximum object size: refers to the size of the internal object code buffer. 
This is normally set to 65536 bytes (64k) but if you are short of memory in the 
machine you can set it smaller (say, to 16000 bytes). If ArgAsm ever reports a 
fatal error because the object code overflowed the buffer then you can make the 
buffer bigger. It should be bigger than the maximum possible size of your object 
code. You can leave a fair margin, so guess on the high side. 


The Macro definition size: refers to the size of the macro definition buffer where 
your macros are stored. This contains all the text enclosed within your 
MACRO/ENDM definitions. If you get errors saying that the macro table is full, 
you know to increase this buffer. In most cases 16000 bytes is adequate, but if you 
are writing large macros you may want to increase it. 


The Header filename: is a special Include file at the start of your source code. It 
has the same effect as having an Include directive on the first line of your source 
code. 


The INCDIR path list: allows you to specify a list of directories (separated by 
+’s) from which Include files will come. This is the same as the INCDIR directive 
within your source code. 


The Optimise: option allows you to select whether ArgAsm will attempt to 
optimise any instructions it thinks could be smaller or faster. It will always ensure 
optimisations are safe and will report how much was optimised at the end of the 
assembly. Future versions of ArgAsm will incorporate more powerful 
optimisation features. Programmers normally want to do the optimisations 
themselves anyway, because they can restructure their code to make it better for 
short branches, etc. 
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The Statistics: option will make a report after assembly telling you useful titbits 
of information such as how big your object code was, how full was the macro table, 
how the disks and assembler performed etc. 


And finally, you get to hit Assemble to proceed or Cancel if you are not yet ready 
to assemble, in which case you will be dropped back into the editor. 
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The Blocks Menu 


To mark the start of a block at the current cursor position, select Start (or hit F1). 
A block is only valid when it has a Start and an End defined. This block will be 
shown in highlighted text. 


To mark the end of a block at the current cursor position, select End (or hit F2). 
All text between the start and end of block will be highlighted. Once marked, 
blocks can be saved, deleted, copied or generally played about with. 


Once marked, you can save a block with Save (or hit F3). This will prompt for a 
filename with a file requester just like Saving a file. 


To Copy a block to the cursor position, select Copy (F4). This will insert the block 
into the text as if you typed it in again at the cursor position. The original marked 
block will remain untouched and will still be marked. 


To Paste in a block that has been previously remembered, select Paste (or hit F5). 


To Delete a block, select Delete (or hold Shift and press F3). This will remove 
the text contained within the block, and will destroy any markers. 


To Remember a block for later pasting, select Remember (or hold Shift and press 
F4). This copies the block into the Paste buffer but leaves it intact in the source 
file. 


To Cut a block for later pasting, select Cut (or hold Shift and press F5). This first 
copies the block into the paste buffer and then deletes the block from your source 
code. 
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The Special Menu 


To take a Snapshot of what you are doing so that you can come back to it later in 
the same state, select Snapshot. This saves off ArgAsm’s internal information so 
that it remembers all the windows you had open (and their position), all the files 
you had loaded, and the text that was in all the requesters. 


A simple programmers’ calculator is built-in by calling ArgAsm’s expression 
evaluator with the Evaluate option. You can type out little sums and get the 
results back in hex, decimal, binary and octal. 


ArgEd’s user configurable Preferences are altered by selecting Preferences. 
These can be saved out so that every time you run ArgEd it sets things up just the 
way you like it. 


Preference Options. 


There are a number of on/off gadgets where you can select whether various 
features are enabled. Auto Fullsize instructs ArgEd to open up the largest 
possible window whenever you run it. Status Line will draw up a status line on 
the bottom of each window containing the line and column number that the cursor 
is on, and also how many bytes the file takes up. Auto Indent allows ArgEd to 
insert a tab (or whatever indent you last used) every time you press RETURN. 
The Slider Bar will select whether ArgEd displays a vertical slider bar on the right 
hand side of each window. This bar can be dragged or clicked on with the mouse 
to scroll the screen around. Auto Snapshot will automatically perform a Snapshot 
each time you Quit ArgEd. This allows you to continue where you left off, 
provided that the Auto Load option has also been enabled. 


Note: scroll and paging speed will be affected by the slider bar and status line on 
the screen. If you want fastest possible text manipulation turn these options off, 
alternatively if you want to know where your cursor is (and lets face it, who 
doesn’t) leave them on. 


The Arg.Inf preferences file 


ArgEd’s preference settings are stored in a file called ’Arg.Inf in the current 
directory. If it is not found, ArgEd will pick sensible defaults and you can then 
Save your preferences again. 


If you ever have trouble with your preferences simply delete the Arg.Inf file before 


running ArgEd. This can happen if you are upgrading to a new version of ArgEd 
and the internal variables have changed format. 
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Source code text format. 


ArgAsm supports the Motorola and Commodore standard line format for source 
code text in a source file as defined by Metacomco. This is also compatible with 
most other Amiga assemblers including Devpac and CAPE as well as a number 
of PD offerings. 


Assembly Source code line format. 


Source code lines may contain any or none of the following: a label, an instruction 
or directive, some parameters, and a comment. Lines may also be intentionally 
left blank (ie: just a linefeed character), or may consist of just a comment with no 
instruction or parameters at all. 


A typical line of text in a source file looks like this : 


Label Instruction Parameter Comment 

eg: 

frog clr.| do * Clears DO reg. 
moveq #0,d0 So does this 

1$ move.| #Zero,DO ; And this too! 

.prg st do * This doesn't. 

* This line only contains a comment. 

; Me too 


As you can see from the examples, there is a TAB character between each field. 
You can use any amount of White Space characters between each field, but we 
recommend you use a TAB because it spaces things out nicely, and a single tab is 
faster for ArgAsm to parse than a series of spaces. 


Labels should always start at the first character of the line. If you don’t want a 
label on the line, then use a TAB to ensure that the Instruction field is not at the 
start of the line. You can optionally terminate a label definition with a colon (:) 
character for compatibility with older assemblers, but this is unnecessary. Labels 
usually start with an alphabetic character (eg: A-Z) in lower or uppercase. You 
can also start them with Underscores (_) for C compatibility, or dots (.) for textual 
local labels. The remainder of the label can contain any alphabetic or numeric 
characters eg: A-Z, 0-9. Numeric local labels can only contain the digits 0-9 and 
must be followed by a Dollar $ sign. 
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Labels are not required on source code lines unless you want them there. This 
might be because you will reference that line from elsewhere in the source code 
(eg: A subroutine call), although some directives require a label to be present (eg: 
EQU). 


Examples of good labels are : 


frog, frog, Frog2, frog:, crunchy_frog 


Good Local labels are: 


100$, 999$, .10, .frog 


These are bad labels because they either don’t start with an alphabetic character, 
or they contain illegal characters: 


2frog, frog*, fr+og, spring-surprise, its(pining 


The Instruction field of a line of source code contains any valid 68000 instruction, 
macro call or directive. eg: MOVE, CLR, or PAGE. In addition, they may 
contain the size parameter separated by a full-stop from the instruction itself, eg: 
MOVEM.L, or BRAS. Valid 68000 sizes are .B for Byte, .W for Word, .L for 
Long, and .S for Short. Instructions must always follow a TAB (or any other 
whitespace) character, which would itself have followed a label at the start of the 
line if one was required. 


The Parameter field of a line contains any operands that may be required by the 
instruction or directive. This field is not always used by some implicit instructions 
(eg: RTS, or NOP). For instructions that require more than one operand they 
must all be specified close together separated by a comma. No Spaces or TABs 
are allowed until the end of this field, as that would signify the start of the 
Comment field (as per the Motorola standard). 


The Comment field is totally ignored by the assembler, which simply skips over it 
to find the start of the next line to continue assembling. You can put any 
comments to yourself about what your code is doing, or how it works its magic. 
A comment starts after the parameter part of the line, provided you put a 
whitespace (eg: TAB) to separate them. You may start your comments with an 
asterisk (*) or semi-colon (;) but this isn’t required as the Motorola standard 
dictates that a comment starts immediately after a blank in the parameter field. 
In addition, you may have a comment on a line on its own by starting the line with 
an * or ; instead of alabel. The entire line will be treated as a comment so do not 
put any instructions or directives there. 
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Case Sensitivity. 


Allinstructions, directives and registers can be typed in either lower or uppercase 
(or if you are feeling weird, a mixture of the two!). Its really down to personal 
preference, but we prefer lower case, because it appears friendlier. The exception 
to this are Labels of any form (eg: equates, program labels, register equates and 
macro names). These are usually Case Sensitive, which means that ’Frog’ is 
different from ’frog’ and so too is "FROG’. You may override this default by 
setting the case insensitive option (OPT C- in your source code), which will 
uppercase all labels for you. This has disadvantages if you wish to use a LINKER 
with other people’s object codes, so try to keep your labels case sensitive if you 
can help it. 


Addressing Modes. 


These are the Addressing Modes that are supported by ArgAsm. They conform 
to the Motorola standard and are listed overleaf as a summary for reference 
purposes. with a few small examples. 
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Addr Mode Explanation 


Dn Data Register Direct 
eg: d3, dO, d7 

An Address Register Direct 
eg: a2, a6, sp 

(An) Address Register Indirect 
eg: (A4), (A1), (SP) 

(An) + Addr Reg Indirect with Post Inc 
eg: (A3) +, (AO) +, (SP) + 

-(An) Addr Reg Indirect with Pre Dec 
eg: -(A4), -(SP), -(A1) 

d(An) Addr Reg Indirect with Disp 


eg: 100(A3), 4(SP), 1000(A6) 
d(An,Rn.s) Addr Reg with Index 
eg: $100(A3,D0.W), 4(A0,A1), (A3,D0) 


d.W Short Absolute Address 
eg: 4.W, 1000.W, -4.W 

d.L Long Absolute Address 
eg: $DFF180, 32788, $bfe001 

d(PC) PC Relative with Disp 


eg: 1000(PC), *-2(PC), 0(PC) 
d(PC,Rn.s) PC Relative with Index 

eg:  100(PC,D0.W), 255(PC,A0), (PC,D0.W) 
#d Immediate data 

eg: #100, #1000, #%1010101 


Inthe above sequence, d is a displacement or number, nis a register number (from 
0 to 7), An means an address register from AO to A7, Rn is either an Address or 
Data register, and s denotes the Size W or L (Word or Long), the default is Word 
sized for most instructions and addressing modes. Disp means Displacement, Inc 
and Dec mean Increment and Decrement respectively. 


ArgAsm will allow you to leave off the initial displacement from any Indirect 
addressing modes that normally require a displacement and will insert a zero in 
there when assembling, eg: (A1,D0) would assemble into 0(A1,D0). Similarly you 
can leave off the displacement from any of the PC relative addressing modes, and 
an asterisk (current PC) will be assumed. Eg: (PC) will become *(PC) etc. 
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Everything you wanted to know about Labels. 


There are three types of Label in ArgAsm, all of which can be used to mark parts 
of your code as subroutines or places of reference. The types are; 


Real Labels, eg: fred, jim and shiela. 
Local Labels, eg: 1$, 999$, and 10$. 
Textual Local labels, eg: .fred, jim, .shiela and also .1, .999 etc. 


ArgAsm will not mind if you feel the uncontrollable urge to terminate label 
definitions with a colon (:) character. But please try not to make a habit of it :-) 
It reminds us too much of those old Sixty Eight K Assemblers that have no 
formatting or neatness abilities. 


What are Local Labels? 


Local Labels are used at times when you honestly cannot think of a real label name 
to put there. Try as hard as you might, you have exhausted all potential 
abbreviations for what the subroutine was supposed to do, and simply cannot find 
any more swearwords with numeric suffices to put as a temporary label halfway 
down a routine. Also, you may have run out of frog’s, froggy’s, fish’s etc. At times 
like these, it is a wise idea to start using Local Labels. They may take some of the 
fun out of label naming, but at least they are quick to generate. For example, 
There is a little known (or used) convention, that 999$ is usually the last label in 
a small subroutine that way you can branch to it easily. Of course there are those 
who argue that something little known and little used cannot be a convention? 


A Local Label is only Local when used wholly inside the bit of code separated by 
next and last real (ie: non-local) label you defined. This is a Limited Scope label 
and can be reused as often as you wish with the same name or number provided 
you are using them after a new real label. For convenience, we provide the nnn$ 
type of local label which is a standard in the Amiga community, but this is limited 
to numeric digits only. We have also implimented textual local labels that start 
with a dot (.) in a compatible way so that the two can be used interchangeably. 
eg: .1 is the same label as 15, similarly .321 is the same as 321$. Naturally .fred 
has no nnn§ alternative, because of the limit of only numeric digits allowable in 
nnn$ local labels. 
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Scope of Labels. 


Some older technology Assemblers on the Amiga have a lot of different symbol 
tables for each day of the week, phase of the moon or number of characters in the 
label. We prefered the more useful approach of having just one symbol table. It 
makes the code much more cleaner, and faster too. But we had to insert some 
logic to separate labels of a similar name that were to be used in different contexts. 


Any normal label value, whether it was defined in the program code, or by an 
equate (EQU) cannot be redefined anywhere else. It is set once, and stays at that 
value. If you want to be able to change the label’s value you can use the SET 
directive to initially define it, and can then successively redefine it (with SET) 
anywhere you want. This is useful for setting up counters or loops in conjunction 
with macros. 


You may define a Label to be equated to a Register by using the EQUR directive. 
This allows you to use that label as if it were a register in the rest of the code. All 
register equates must be defined before they are used, and once defined that label 
name cannot be used by a symbol value elsewhere (eg: for an EQU), so take care 
not to use register equates and label equates that clash. 


Macro label names can have the same name as a symbol label name without 
clashing because they are context sensitive. ie: Macro labels can only appear as 
instructions or directives. They are never used within expressions, or operands 
which is where symbol labels would be used. So take care not to be confused by 
this feature. 
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Beware of Auto Alignment. 


The 68000 Program Counter must be a multiple of two (known as ’Even Aligned’) 
to execute instructions. This can be assured by using the EVEN directive after 
every time you incorporate byte data into your code, eg: after every DC.B or DS.B 
statement. Failure to do so will generate an Address Error exception which will 
probably give a GURU or System Message on your machine, even with a 68030 
processor ! 


ArgAsm, like most modern assemblers, will auto-align the program counter to be 
on an EVEN boundary if you try to put an instruction or word/longword data 
word onto it. This feature in itself is harmless, and in fact helps sort out most 
problems where the programmer forgot to do a CNOP 0,2 or an EVEN after they 
were using an odd number of bytes of data in their code. 


eg: 
* start at location 0. 
dc.b 0 * the pc is now at loc 1, ie: odd 
frog 
dog nop * This nop starts at loc 2 


* because it was Even Aligned. 


Note that the label frog will be equal to 1, since it is immediately after the odd pc 
left by the dc.b. However, label dog will be equal to 2, because the NOP was 
even-aligned from 1 to 2 and its corresponding label will be as well. 


But have a look at this piece of code... 


* Start at loc 0 again 
cat dc.b 0 * cat=0, and leave pc at 1, ie: odd 
frog nop * pc is Even Aligned to 2 as usual. 


The problem to watch for is if you did not have two labels after the de.b, with there 
being only one label it will be autoaligned because of the NOP even if you were 
expecting it to be the value of the pc after the dc.b. eg: you would expect frog-cat 
(frog minus cat) to be equal to 1, but it will be 2 because the frog label was 
autoaligned. To solve this, either do an EVEN after any use of dc.b’s that might 
potentially be odd, or have multiple labels after an odd byte entry, one label that 
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represents the end of the set of bytes, and not to have any code next to it. The 
other label will represent the start of the following code, which will be 
Even-aligned. 


Do be wary of this Auto Alignment potential for misuse 
as it is known to have caused many a debugging 
headache in days gone past. We have implimented 


hat we believe is the correct way of handling thi 
problem, and it tallies with the way most other as 
semblers handle the same situation! 
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Expressions. 


ArgAsm utilises a full 32 bit integer expression evaluator of a form similar to that 
used in high level languages. Complex expressions are allowed containing all the 
usual intricacies including unlimited parenthesis levels (brackets), prioritised 
operators, unary operators, and of course logical operations. 


Most Expressions will take the form of : 


[unary minus or plus] [number] [operator] [num- 
ber] etc 


It is important to note that expressions are either Absolute, or Relative. Absolute 
Expressions are those where you specified the numbers directly or from Equates 
(EQU, SET etc). Relative Expressions are those where they refer to labels that 
are in of the program code itself, and as such their values are not known until the 
program has been loaded by AmigaDOS. In general, it is safe to do any type of 
expression made up of Absolute values. But you must be careful when mixing 
Relative and Absolutes together. For instance, frog+2 is a perfectly valid 
reference even if frog was a bit of the program code andis thus relative. But frog*2 
is not, since the address of frog is not known at Assembly time, and will only be 
confirmed when the program is loaded at runtime. 


The list of operator precedence in ascending order of priority : 


__ Symbol _ Function 


Equals 
Less than < * > are the same level 
Greater Than 
Addition + & - are the same level 
Subtraction 
Multiplication * & / are the same level 
Division 
Bitwise AND 
Bitwise OR - 
Bitwise XOR 
<< Shift Left << & >> are same level 
Shift Right 
Bitwise NOT 
Unary Minus 
Unary Plus 


> 77 *' 4FVA I 


UV A 
Vv 


' 


+ 
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The Unary operators + and - are the highest priority. 


Expressions are always evaluated from left to right unless operator or parenthesis 
priorities dictate a different order. 


You can override the priority of operators in an expression by judicious use of the 
parenthesis brackets ( and ) to surround the parts of the expression you want at 
a higher priority. You can nest the parenthesis an almost unlimited amount deep 
(255 levels is pretty deep). 


Allexpressions are performed using signed 32 bit integer arithmetic. No overflow 
conditions are checked. 


Expressions must not contain any spaces or delimiters of any sort, as this would 
signify the end of the expression (and the start of a Comment under normal 
Motorola rules). 


Using external references inside expressions 
(XREF’d symbols). 


Due to a Linker format restriction, only simple expressions are allowed when 
dealing with external references. You can only add or subtract numeric values to 
external references, any other operation would be meaningless since Amiga 
Linkers do not support expression evaluation at this time. 


Any symbols that are to be used as external references should be declared before 
use, by the XREF directive. 


Once a symbol has been referenced by any part of your sourcecode, its Type is 
recorded. If it wasn’t XREF’d in advance of that time, then it can’t be at a later 
date. The best place to put your XREP’s is at the start of your source files. (The 
same goes for Macro definitions, and EQUR’s etc). 


Bases for Numbers and Constants. 
ArgAsm supports a full range of base numbering systems, including the ever 
popular hexadecimal, and decimal, but also the less popular binary and octal 
bases. Also, ASCII character constants are supported. Leading zeroes are not 
required, and are in fact ignored (but trailing zeroes are obviously pretty 
important!) 


Decimal numbers start with a digit, eg: 123 or 95. 


Hexadecimal numbers start with a Dollar $ sign, eg: $100 or $fabc. 
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Octal numbers start with an AT @ sign, eg: @777 or @012. 
Binary numbers start with a Percent % sign, eg: %1010101 or %1111. 


Also, Character constants can be used in expressions by enclosing up to 4 
characters between single or double quotes (’ or "), eg: "DOS" or ’A’. These 
character constants are Right Justified into the constant. Ie: The last character 
in the string will be the lowest significant byte of the number constant. 


Inside a character constant you may wish to use the same quote that you were 
using as a delimiter. In this case, two quotes of the same type will give you one 
normal quote inside your character constant. eg: 


"A" becomes A in hex$00000041 

>@ @’ becomes @ @ in hex $40204020 
"DOS", 1becomesDOSin hex $444f5301 
*IT’’S’becomesIT’S’ hex $4954275C 
"A" becomes"A"in hex$00224122 


Special symbol * 


An asterisk * is a special symbol in an expression and is used to mean the current 
Program Counter value (ie: the address of where you are in memory in your 
program). This is usually a relative value. Do not be confused between * as the 
PC, and * as multiplier operator (or indeed * as a comment!). Since it is not useful 
to multiply the PC by any value, this confusion will not crop up much. 


eg: 

bra.s = ; Loops infinitely 

lea *+10(pc),a0 
Supplied on the ArgAsm distribution disk is the BLINK linker written by the 
Software Distillery. A later version of BLINK (curiously versioned 5.04) is 


available from Lattice as part of their C Compiler package. Blink is largely 
compatible with Commodore’s ALINK only faster. the CLI usage for Blink is : 


1> BLINK prog1.o,prog2.0 TO Prog 


Further power-user features of blink can be discovered by typing BLINK on its 
own, 
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ArgAsm Directives 


So as to minimise any alteration to your existing source code, we have made 
ArgAsm very closely compatible with its contemporaries. These include Hisoft’s 
Devpac v2, Inovatronic’s CAPE v2, and Metacomco’s ASSEM v10 and so (alas) 
our supported Directives list is rather long and contains numerous different 
functions of a similar nature. You have CAPE to thank for the myriad of extra 
non-standard directives whereas Devpac’s extensions were more subtle but 
equally powerful. Either way, we have implemented almost all of them (for 
completeness). 


END 


This is an optional directive that terminates the assembly of the current source 
file. Assembly will terminate when the end-of-file is reached so the END directive 
is mainly for causing premature endings in conjunction with conditionals. Note: 
Any ENDs in Include files will only terminate THAT specific file, and return 
assembly to any previously active source code. 


INCLUDE <filename> 


This will read in a file from disk and insert the named source code into the 
assembler at the exact position of the INCLUDE in the current source as if the 
text was already there. The filename can optionally be enclosed in double or 
single quotes if it contains any characters likely to confuse the assembler or 


AmigaDOS (eg: Spaces). The filename can incorporate a full drive name, device, 


pathname, assigned path or any other legitimate AmigaDOS filename. 
cg: 


INCLUDE myheader.i 
INCLUDE "Includes:hardware/blitter.i" 


Includes can be infinitely nested (as much as available memory allows) but we 
recommend you to keep the nest level as low as possible for your own sanity and 
debugging ease! 


The filename specified is loaded either from the current directory or from the 
directory specified by a previous INCDIR (INClude DIRectory). Ifthe Include 
filename contains a drive or device name (text followed bya COLON: character) 
then this overrides any INCDIR directive and loads the file from the specific area 
of the disk! 
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ArgAsm will always make best use of available memory, and try to load the entire 
INCLUDE files into memory in one go. If memory is lacking, ArgAsm will 
complain bitterly, and you will either have to buy more RAM, or find a way of 
splitting your files into smaller more manageable chunks. A future version of 
ArgAsm may be more able to cope with low memory assemblies, but the present 
version was designed for performance rather than memory efficiency. 


INCBIN <filename> 


This will read in a binary data file (such as screen data, sprites, sound samples 
etc) directly into the current position in the object code and update the Program 
Counter accordingly. Beware of odd-length files that might cause the PC to be 
incorrect afterwards. ArgAsm will automatically align the PC for your safety. 


EVEN 


The 68000 series of microprocessors cannot execute instructions that are on 
ODD boundaries (not even the 68020 or 68030!) This directive will align the 
Program Counter to be EVEN (ie: a multiple of 2), and is mainly used after byte 
directives like DC.B and DS.B that may have left the PC ina ODD state. Note: 
ArgAsm tries to autoalign instructions so that the PC to be EVEN all the time 
so this instruction is largely for compatibility with previous assemblers. See the 
warning about auto-alignment in the Labels section. 


CNOP <offset>,< alignment > 


This will align the Program Counter in any custom manner you want. If you 
wanted to Word Align the PC, you would do a CNOP 0,2 and similarly to 
Longword align you do a CNOP 0,4. The Offset allows you to index into your 
alignment. Thus CNOP 2,4 will place the program counter 2 bytes into the next 
Longword boundary. You can within reason have any offset and alignments you 
want, but avoid silly numbers (that are too big!) 


ORG <address > 


This will force the Program Counter to be on a specified absolute address and is 
mainly for creating Absolute Code for use on a target machine. We do not 
recommend using this directive on a native Amiga unless you know a lot about the 
memory organisation and disable the Amiga OS (a brave move!) This is mainly 
used by Games Programmers. 
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DB < expressions > 
DW < expressions > 
DL < expressions > 


Cape compatible alternates of DC.B, DC.W and DC.L (see below). 


DC.B < expressions > 
DC.W < expressions > 
DC.L < expressions > 


These directives are for defining constants (data areas) of the specified size into 
the program at the current PC address. The Expressions can be separated by 
commas to have as many as you can fit on one line! Expressions can be any 
combination of labels, numeric values, or textual strings in quotes. 


Be wary of any spaces in your DC expressions, as they signify comments and can 
lead to many a bugette! 


eg: 
dc.b If,"Hello there Frog",O 
dc.w 65535 
dc.| 10000,1000,100,10,1 
DS.B < expression > 
DS.W < expression > 
DS.L < expression > 


These directives Define Space rather than a constant. It will reserve space of the 
desired amount (filled ‘ith zeroes), and is used for preinitialising large buffer 
areas. eg: DS.L 10 will reserve 10 longwords (40 bytes of zero) of space whereas 
DC.L 10 will put in the longword value 10 into memory! Note the difference, as 
it can lead to many a typo bug in those early morning hours! 


eg: These DS’s will all reserve 1000 bytes of space. 


ds.b 10*100 
ds.| _ 250 
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ds.w 1000/2 


The Expression must evaluate immediately with no forward referenced labels! 


Be careful with large DS’s that might overflow the object code buffer! 
DCB < number >, < value > 


This directive allows you to define a constant block. Unlike DS, a DCB will allow 
you to specify the filler data as well as the amount of times it will be copied. eg: 
DCB.B 100,$ff will reserve a block of data 100 bytes big each containing an $ff. 


FAIL 


This directive will prematurely terminate the assembly with an error message. It 
is usually used in conjunction with conditional IF statements to check for errors 
or lack of data, or incorrect macro parameters. 


OUTPUT <filename> 


This directive specifies the filename that will be used to write out the object code 
when the assembly has completed. It can be set on the command Line, or inside 
your source file. Note: It can only be set once. 


OBJFILE <filename> 
The Cape compatible version of OUTPUT. 


__ G2 (reserved symbols) 
ArgAsm 


These are special reserved symbols that you can check to see which assembler 
you are running on. Best used in conjunction with conditional assembly. 


REPT < expression > 


This directive will repeat the block of code contained between it and the next 
ENDR a specified amount of times. Best used for opening up small loops for 
performance purposes. Repeated loops cannot be nested. 
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ENDR 


Closes the last part of the source code to be repeated (see REPT). 


LIST 


This directive on its own will turn on the assembly listing output. You can use 
NOLIST to turn the listing off at any time afterwards. 


List will also accept ON, OFF, + and - as alternative forms of turning the 
assembly listings on and off. 


NOLIST 
This will turn off the assembly listing output. 
PLEN < expression > 


This will set the page length, ie: The number of lines that fit onto each page of 
your printout. Can be between 12 and 255, the Default is 60. 


LLEN < expression > 


This will set the Line LENgth, ie: The number of characters that fit onto each 
line of your printout. Can be between 38 and 255, the default is 132. 


TTL < title string > 


This will set the title of your printout and will appear at the top of each page of 
your printout. 


SUBTTL  <subtitle string > 


This will set the subtitle that appears under the title on each page of your printout. 


SPC < expression > 


This will leave a specified number of lines gap in the Assembly Printout. 


A a 
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PAGE 


This will eject the current page on your printer output. 


<label> EQU <value > 
<label> = <value > 


Allows you to define a label to be a specified value or expression. It must evaluate 
immediately and cannot contain a forward referenced label. 


<label> EQUR < register > 


Allows you to supply names for your favourite registers, and then use them in the 
rest of your source code as their newfound names. We do not recommend this 
feature as it tends to make code unreadable, and also slows down the Assembly. 
It is implimented for compatibility reasons only. 


<label> SET < expression > 


Allows you to define a label, much like EQU but has the added feature of being 
redefinable at any time. Has hundreds of uses, but we can think of only one right 
now... use it as a counter inside Macro’s or Repeat loops by saying : 


frog set 0 
rept 100 
frog set frog+1 
dc.w frog 
endr 


The above will generate 100 words in memory numbered 1 to 100. 


<label> REG < register list > 


This allows you to name lists of registers for use in MOVEM instructions. Its 
primary use is to ensure you stack and unstack the same registers when entering 
and exiting your subroutines. 


<label> RS.B < expression > 
<label> RS.W < expression > 
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<label> RS.L < expression > 


This Reserves Space in a Coun:cr allowing you to define lists of offsets from the 
start of a data structure. It does this by incrementing a Counter used only for the 
RS set of directives. It does not affect your code or data in any way. Best used for 
interfacing with other people’s offsets in their data structures (eg: Commodore 
Include Files). 


RSRESET 


This resets the RS counter to zero, and is usually used at the start of a data 
structure list. 


RSSET < expression > 


This sets the RS counter to a specified amount, and is usually used to start the 
RS’s at a position inside a structure. 


RS <reserved symbol > 


This contains the current value of the RS counter. (It starts with two underscore 
characters). 


G2 < reserved Symbol > 


This contains the version number of GenIm2 that we were using for test, and is 
intended to pretend to be Devpac compatible so that sourcecode that assembles 
under GenIm2 will assemble under ArgAsm too. 


__LK < Reserved Symbol > 


This is a Devpac compatible symbol that currently gives a 3 if the code file format 
type is Linkable, and a 4 if it is Executeable. 


ArgAsm Page 43 


ArgAsm Options Settings. 


Devpac compatible options. 


OPT <optionlist> 


This allows various option settings to be altered within the source file. Most of 
these can also be defined from the CLI at the start, or will use sensible defaults. 
Options are usually a single letter followed bya + or - sign to signify On and Off 
respectively, like C+ or D- and multiple options can be done on the same line 
separated by commas. 


OPT C+,L+,W- 


The above line sets case Insensitivity ON, Linking object code ON, and Warnings 
OFF. 


Supported Options 


C - Case Sensitivity On/Off. 


When Case sensitivity (or Independance) is turned OFF, all labels are converted 
into upper case before use, which allows you to randomly use either upper or 
lower case in your code as it all gets turned into upper case anyway. If you can 
do without, we recommend you keep case sensitivity ON because it produces 
easier to read labels, especially when they consist of multiple words (eg: which is 
more readable, ConvertSprites or CONVERTSPRITES?) Defaults to ON. 


D - Debugging Information On/Off. 
When the Debugging flag is turned ON, the Assembler will output all symbol 
definitions whether they were XDEFed or not into the output file, that way they 


can be accessed by a monitor or linker for debugging purposes. This makes the 
object file significantly larger than usual. Defaults to OFF. 
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E - Error list output. 


ArgAsm will buffer up to 255 error messages, and then report them at the end of 
Assembly if this option is enabled. 


L - Linker Mode On/Off. 


When the linker mode is turned ON, you can use the XDEF and XREF directives 
to access external references in other object files. The object files are written in 
a format suitable for an Amiga compatible linker, eg: (ALINK, BLINK etc). 
When turned Off, the object files are generated as Executeable, so a linker isn’t 
necessary to convert them into runnable AmigaDOS files. This option can be 
chosen only at the start of your source file, and cannot be changed afterwards. 
Defaults to ON. 


M - Macro Expansion in listings On/Off. 

When Macro Expansion is turned ON, the Assembly Listing will contain every 
line that is inside Macro definitions. When turned OFF, you will only see the 
MACRO name, and not its contents. You can turn this feature on and off 
anywhere anytime. Defaults to OFF. 

O - Optimisation. 


This controls whether ArgAsm will attempt to optimise certain instructions with 
shorter faster versions. Defaults to OFF. 


OW - Optimisation Warnings. 


This allows you to inhibit ArgAsm’s warnings when it optimises your code. 
Defaults to ON. 


S - Symbol Table Listing. 

When enabled, this will output a symbol table listing at the end of any listing 
output. Only the last S option found before the assembly is finished will have any 
effect. Defaults to OFF. 

W - Warnings. 


You can disable Warning error messages from being reported if you know what 
you are doing and don’t want to be bothered by them. Be careful! Default to ON. 
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Cape compatible options. 


ADDSYM 
This adds symbols to the output file, and is the same as an OPT D+ 


DEBUG 


This adds debugging information to the output file, and is presently the same as 
an OPT D+. Ina future version of ArgAsm it will control the Lattice extended 
source level debugging information. 


OPTIMON 

This turns on Optimisations and is the same as OPT O + 
NOOPTIM 

This turns off Optimisations and is the same as OPT O- 


NOOBJ 


This disables any object code generation for this source file and is similar to doing 
a -B at the CLI level. 
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Conditional Assembly directives 


In general these operate in a similar way to the 68000-style Bcc branch condition 
codes and hopefully make them easy to remember for those who actually know 
68000, and if you don’t, now is a good time to learn. The IF directives are 
immediately followed (without a space) by a condition like IFEQ or IFGT. The 
supplied expression is evaluated and then compared with zero (0). The resulting 
condition dictates whether the source code is ignored or assembled until the next 
matching ENDC. The expression in a conditional MUST evaluate without 
forward referenced labels. Infinite nesting of conditionals is supported, but 
please watch yourself for losing track of your IFs and ENDCs. ArgAsm will keep 
a count of the nest level, and if a mistake should occur (an imbalanced IF and 
ENDC pair) a suitable error message is reported. 


Thé main use for conditional assembly is in producing code that contains extra 
bits for debugging, eg: printing out vital information for the programmer to see. 
An equated label at the start of your sourcecode could be set to 0 or 1 depending 
on whether you wanted the debugging code included when you assemble. 
Conditionals can also be used for generating portable code to run on different 
assemblers, or for writing code that runs on different machines. 


IFEQ < expression > 


Checks to see if the expression is EQual to zero. 


IFNE < expression > 


Checks to see if the expression is Not Equal to Zero. 
IFGT < expression > 

Checks to see if the expression is Greater Than Zero. 
IFGE < expression > 

Checks to see if the expression is Greater or Equal to Zero. 
IFLT < expression > 


Checks to see if the expression is Less Than Zero. 
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IFLE < expression > 


Checks to see if the expression is Less than or Equal to zero. 


Note: On older assemblers that lack these flexible conditions, they usually 
implemented IF on its own, which is equialent to our IFNE condition. 


Further Conditionals 


IFD < label > 
Checks to see if the specified label exists. 

IFC ’string1’,’string2’ 
Checks to see if the two strings match. 


IFND < label > 


Checks to see if the label doesnt exist. 


IFNC ’string1’,’string2’ 


Checks to see if the two strings don’t match. The strings are often supplied in 
Macro arguments to check validity. 


ELSEIF 


This inverts the current conditional flag, and allows an ELSE portion of a 
conditional to be incorporated into the IF...ELSE...END structure 


ENDC 


This terminates a Conditional Assembly portion. After which, Assembly resumes 
as normal. IFcc-ENDC pairs can be nested as deeply as your heart desires. 


ENDIF 


The Cape compatible version of ENDC. 
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MODULE <modulename> 


This directive defines the name of the current object module, the default if you 
don’t bother is rather imaginatively named "ANON_MODULE'" for historical 
reasons. Modules are useful for deciding which parts of a library will be used by 
the linker. If you never use this directive in your life be assured you won’t missing 
anything. 


SECTION <Section name>, <type> 


Some parts of your program may be required to load into chip memory (for 
instance, sprite or sound data) so you often want to have different named sections 
of your code loading into different places. The Section directive allows you to 
name parts of your program. Like named sections will be coagulated together 
before being written to disk. Valid code-types are: CODE, DATA and BSS. In 
general, Code is your main section and is used by all your code (and sometimes 
data). The Data section is purely for data and must not have executing code in it 
(since it could potentially be shared by multiple programs running at the same 
time), and the BSS section is uninitialised storage space that your program can 
use for scratch space. If you want your program to be able to run Resident, then 
you cannot have a BSS section, and must dynamically allocate all the memory you 
require inruntime. Also, an underscore after the code type allows you to specify 
Chip (useful for sprite and audio data) or Fast memory, eg: 


section MySprites,code c 


Public memory (the default type) will load into Fast memory if there is any 
available, failing that it will load into Chip memory. Unless you are really sure 
you want it, Never specify Fast memory explicitly, as you cannot guarantee people 
will have any! 
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Symbol Imports and Exports 


XDEF <label>,<label> etc 


This allows you to specify which labels are to be exported into the object code for 
reference by other object codes during the Linking process. All labels to be 
exported must be XDEF’'d first! It is best to put all your XDEFs at the start of 
your program where they can be found and modified easily. 


XREF <label>,<label> etc 


This specifies what labels are to be imported from other object codes during 
linking. All XREFs must be specified before the labels are used, so yet again it 
is recommended to have all your XREFs at the start of your program. 
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Copper instructions. 


The Amiga has a co-processor chip called The Copper that can perform screen 
synchronised control over the Amiga custom chips. It is best used for dynamically 
changing colour palettes, altering resolutions and screen positions, etc. The 
Copper has a few instructions of its own that are usually implimented on other 
Assemblers with macros in hardware Include files. For such a powerful chip to 
be so inefficiently programmed seemed strange to us, so we implimented the 
popular Copper macro instructions CWAIT, CSKIP, CMOVE, and CEND as 
part of ArgAsm’s vocabulary of instructions, that way making them much faster 
to assemble and more usable than the older macro counterparts. Although they 
are macros, you can treat them like instructions. 


Note: The Copper macros are provided for the use of constructing copper list 
data tables only. Don’t confuse these Copper instructions with 68000 instructions. 
They are very different such that Copper instructions cannot be executed by the 
68000 chip (and vice versa). 


For more details of Copper instructions, their usage and abilities see the Amiga 
Hardware Reference Manual. 


CWAIT X,Y 


This waits for a given electron gun beam position before continuing with the next 
copper instruction. X and Y must be between 0 and 255, and the x resolution is 
very chunky. 


CMOVE _ value,register offset 


This moves a Word value into the custom chip register. The register offsets can 
be found in the Amiga hardware reference manual, and are all currently found 
starting offset from $dff000 in memory. The register offset is a Word, and must 
be even. 


CSKIP x,y 
This instruction skips if the electron beam is past the specified point. See CWAIT. 
CEND 


Terminates your copperlist. 
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Macro handling. 


A Macro is a collection of instructions that are given a name, and can be called 
up by that name at any time in your source code. Macros are there to save typing 
and preserve readability, but when coupled with Conditionals and Parameters 
they provide some great powerful programming features. 


Macros must be defined, usually at the start of your source file, or in a header 
include file. They can then be invoked anywhere in your source code by using the 
macroname as if it were a new instruction. Unlike a subroutine call, a macro call 
puts the entire contents of the macro into your source file whenever you use it. 
Thus macros are faster to execute since they avoid having to JSR and RTS to get 
to them, but of course the penalty is they take up more memory. Whenever you 
use a macro call, the definition is ’expanded’ into your source code as if you typed 
it in yourself. 


Macro’s aren’t just used to save typing in blocks of instructions. They can also be 
used to create tables or data in any format you require. Macro calls can also be 
nested as deep as you want, but the macro definitions cannot be nested at all. 


ArgAsm supports Motorola style macros both to the Commodore Metacomco 
standard, but also including the Devpac extensions that allow up to 36 parameters 
(instead of the usual 10) 


<Label> MACRO 


This is the way you start a macro definition. All lines up to the next ENDM will 
be put aside into a buffer ready for you to call them anytime by using the label 
name in your source code. Macros must always be terminated by an ENDM. Try 
to keep your macros small and flexible, that way you can re-use them in future 
programs and save yourself reinventing your macro wheels all the time. 


ENDM 


This directive terminates the current macro definition started using the MACRO 
directive. There can only be one ENDM per macro definition. 


MEXIT 


This will prematurely terminate the current macro expansion. It is often used in 
conjunction with some conditional checks to make sure the parameters given to 
the macro were correct. 
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NARG < Reserved Symbol > 


In addition to the above directives, there is a special reserved symbol "NARG" (in 
uppercase) available that you can use in your macro expressions at any time. It 
returns the number of parameters passed to your macro. This is commonly used 
to make sure your macro was passed the correct number of parameters in 
conjunction with some conditionals and the MEXIT directive. 


Outside a macro, NARG returns 0. 
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Macro expansions & 


parameters 


To expand an already defined macro, you use its name, followed by up to 35 
parameters separated by commas with no spaces. eg: 


FRED 100,200,300 


Inside the macro definition, you would refer to each parameter with a backslash 
(\) character and followed by the numbers 1 to 9, then A to Z to correspond to 
parameters 1 to 9, then 10 to 35. As the macro is expanded, any occurrences of 
backslash parameters are substituted with the actual text of the parameters. That 
way, you can have words, or instructions or numbers as your parameters. To 
include spaces or commas in your parameters you must enclosed the whole 
parameter in angle brackets eg: < THIS IS PARM 1, ok? >. 


There is also a special parameter \0 which refers to the Size given in the macro 


call. Like most Motorola instructions, it defaults to Word sized (W) if no size was 
specified in the macro invocation. EG: 


FRED.L 100,200,300 
Would return \0 as an L, so your macro definition would look something like... 


FRED 
MACRO 
MOVE.\0 #\1,D0 
MOVE.\0 #\2,D1 
MOVE.\0 #\3,D2 
ENDM 


The above macro, when called would put a Longword of 100 into dO, 200 into d1 
and 300 into d2 respectively. 


but: 
FRED 10,50,-100 
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.. would expand to a Word sized macro (since \0 defaults to W and no size was 
specified) and would load a Word of 10 into dO, 50 into d1 and -100 into d2 


Other Backslash functions... 


\@ gives a unique _nnn text string where ’nnn’ is anumber incremented each time 
a macro is used. This allows you to have unique labels embedded within your 
macro since if you used normal labels then your macros would forever be trying 
to redefine labels that already existed. 


eg: 


FRED |= MACRO 
CMP.L #\1,D0 
BGT.S FROG\@ 
RTS 

FROG\@ 

MOVEQ #0,D0 
RTS 


The above macro, when called with one parameter will insert a piece of code that, 
when executed will check to see if the parameter supplied was larger than DO, 
and if so, DO will be cleared. If the label FROG was used on its own without the 
\@ then you would not be able to use macro FRED more than once because 
FROG cannot be defined multiple times. But using the \@ gives each label a 
unique numeric identifier allowing it to be different on each occasion that you use 
the macro call. 


If you wish to retrieve the value of a symbol inside your macro expansion, you can 
use the \<symbol> to expand it into a decimal number, and \$<Symbol > for 
hex. The symbol must be absolute and already exist to be used in this manner. 


To get a true baskslash (\) character within a macro expansion, you must use two 
backslash characters next to each other, eg: \\ would return a single \. 


In an assembly listing, the macro name is shown whenever you invoke a macro, 
but the actual text of the macro expansions are not shown by default unless you 
use the OPT M + directive to turn on listing of macro expansions. This is because 
macros are usually to save typing, space, and paper and to promote readability. 
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Macro call parameters can be longer than one line providing each line of the 
macro call parameters ends in a comma (,) and the next line starts with an 
ampersand (&) followed by a space or tab, then followed by more macro 
parameters. 
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Error Messages and explanatory notes 


There are four kinds of error and status reports that ArgAsm supports; Warning 
messages, Optimisation Warnings, Errors messages, and Fatal Error messages. 


A Warning message is simply a reminder of a minor error or mistake in your 
source code that ArgAsm has duly noted and ignored since it wasn’t worth 
bothering about. Warnings are primarily there to help you avoid bad habits or 
sloppy programming practices, but the more advanced users will probably want 
to turn these Warnings off. The assembler will continue with the rest of your 
source code quite happily after a Warning message. 


An Optimisation Warning message is a reminder that ArgAsm has optimised an 
instruction, so that you can make that optimisation permanent in your source code 
at a later date. There is nothing harmful about ArgAsm optimising your code, as 
it has a set of rules that it carefully applies. The code will be functionally the same, 
right down to flag settings and which registers are affected. The Assembler will 
continue assembling the rest of your source code, as with Warning messages. 


An Error Message will notify you of any mistakes or problems in your source code 
that need your attention. The assembler will continue assembling your source 
code just in case there are more errors to find, but your object code will be invalid 
and it is not worth trying to execute it unless you are sure that the errors do not 
affect the specific bit of code you will be testing. 


A Fatal Error Message is an error so bad that it is pointless trying to continue 
assembling the rest of the file. These sorts of errors must be fixed immediately if 
you want to get anything assembled. These errors are usually due to outside 
circumstances, like being unable to find a specified include file on the disk, or not 
being able to write out an object file. The Assembler aborts after a Fatal Error, 
and does not assemble any more source code until the problem is fixed. 


In general, ArgAsm will continue assembling your files, counting and 
remembering the errors and warnings for later examination. You have the option 
to display errors as they are found, or display up to 250 of them at the end of 
Assembly. In general, ArgAsm will try and work out where the error was in the 
line of source code, and show the text and highlight the mistake as best it can. If 
the error was in a Forward Reference, then ArgAsm will not display the text of 
the line with the error, and will only display the error message and line number 
where the problem occurred. 


One of the features of ArgAsm are the positive error messages. They don’t just 
tell you whats wrong, they try and tell you why its wrong. Error messages are there 
to enable you to quickly find your problem and easily. Being vague is pointless, 
so ArgAsm tries to be as helpful as possible during its error reporting. 
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In particular, it will try and give useful information as to why an error occurred 
so as to help you fix it more easily. eg: When confronted with a BRA.S (short 
branch) to an address that was too far away, Other assemblers might report "Data 
too large" where ArgAsm would be more helpful and say "Byte Displacement out 
of range by 2 bytes" which would give you more of an idea how to fix it. Another 
example would be if you had used an IF but but forgot the corresponding ENDC 
from your source code. ArgAsm would say "Conditionals aren’t balanced, There 
is 1 more IF than ENDC!". 


If you ever see any Internal Errors (they say "Internal:" at the start of them) then 
please report them to us. These should never occur in normal usage and indicate 
a problem that needs our attention. 


If you ever see any Fatally out of memory errors’ this means ArgAsm has run out 
of memory whilst deep within its expression evaluation routines. If this happens 
often, we suggest you buy more RAM for your Amiga, but in the short term try 
splitting up your source files into smaller chunks and using a master source code 
to Include in all the sub-source chunks. Also, try pruning down the object code 
buffer with the -m cli option. If memory is seriously low, ArgAsm may not have 
enough memory to exit safely again. At times like this, it may even crash. The 
bottom line is; make sure ArgAsm has all the memory it needs for the source code, 
object code, symbols, and macro definitions. 


Here is the ArgAsm Error list, in numeric ascending order by Error Number. 


Most errors messages are self explanatory, though some may have extra comments 
below them. 
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List of ArgAsm Error messages. 


1. Label defined twice 


You may have two labels with the same name. This usually occurs with Case 
Insensitivity. 

2. Too many brackets 

ArgAsm supports up to 255 parenthesis levels. 


3. Missing ( 
4. Bad size, .B, .W, or .L expected 
5. | Dn,Dn or -(An),-(An) expected 


Some instructions like ABCD do not allow the normal collection of addressing 
modes. 


6. Bad address register 
7. Bad data register 

8. Data register expected 
9. Parameter error 

10. Bad register 


11. Fatally out of memory (Internal ...) 

The memory in your Amiga was exhausted before the assembly was finished, try 
saving memory by having a smaller ramdisk, assembling smaller sourcefiles that 
use Include more effectively, and also try pruning down the maximum object code 
buffer size with the -m cli option. 


12. Not enough memory by n bytes. 
This refers to the object Code buffer being full. Try a bigger buffer with the -m 
cli option. See error 58. 


13. Reserved 

14. Bad register 

15. Illegal parameters, try (An) +,(An) + 
16. Operation too large, byte expected 
17. Operation too large, word expected 
18. Data Alterable (ea) expected 

19. Data Addressing (ea) expected 

20. Memory Alterable (ea) expected 

21. Alterable (ea) expected 
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22. Control (ea) expected 

23. Unrecognised addressing mode 

24. Byte displacement: Out of range by n bytes 
25. Word displacement: Out of range by n bytes 
26. Label not defined 


If you reference a label that wasn’t defined later on. 
27. Operand too large, Nybble expected 
28. Operand too large 


29. No label for equate 


This usually occurs as a side effect of trying to do an EQU after a Label Defined 
Twice. 


30. Address register expected 


31. Unrecognised Instruction 
No Instruction, Directive or Macro definition exists of this 
name 


32. Data register expected 
33. Missing quote 
34. Panic! Premature end byte reached 


This should not occur! Report it to us, with an example if possible. 
35. Macro storage space full 


36. Macro definition requires name 
All Macro definitions must have a Label 


37. Nested macro definition 


You may not nest macro definitions 


38. Macro definition not terminated 


No ENDM was found, to terminate the Macro definition. 

39. Only allowed in Macro definition 

40. Unrecognised Instruction 

41. Incorrect delimiting in parameter list 
42. Undefined symbol 

43. Too many parameters (max 35) 
(warning) 

44. Immediate value expected 

45. Value between 1 and 8 expected 

46. Bad size, .W or .L expected 
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47. Register expected 

48. Bad size, word expected 

49. Bad size, byte expected 

50. Garbage following instruction 
51. Bad size, .S, .B, or .W expected 
52. Short branch converted to NOP 


(warning) 

53. Bad size, long expected 

54. XREF’d symbol used in expression 

55. Linkable code option not set 

56. Can’t export symbol 

57. Referenced symbols cannot be XREF’d 
58. Object Code Buffer full! 


Use the Assembly Options in ArgEd or the -m cli option to increase the 
Maximum object code buffer size. 


59. Bad option 


An OPT directive was used with illegal option parameters. 


60. Options must be set at start 
Some options must be set before any code is generated, eg: OPT L + (Linking or 
Executeable mode) 


61. Divide by zero 


You cannot have a division by zero inside an expression. 


62. XREF’d symbol not allowed 
63. ORG must evaluate! 


No forward references or xrefs are allowed for an ORG address. 


64. Page length must be between 12 and 255! 
65. Strange expression 

66. Bad line length 

67. Too many lines 

68. Untitled? 

69. Not implimented yet (alas) 

70. Repeat up to 65535 times 

71. ENDR found with no corresponding REPT 
72. Expected CNOP Offset,Alignment 

73. Nota valid effective address 
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74. Nota valid register list 

75. Expected format: ’String1’,’String2’ 
76. No forward references allowed 
77. Unexpected ENDC 

78. INCBIN filename expected 

79. INCBIN file read error 

80. INCLUDE filename expected 

81. INCDIR filename expected 

82. OUTPUT filename expected 

83. Object filename already specified 
84. File not found 

85. Could not Examine file 

86. File Load error 

87. File Save error 

88. Name expected 

89. Hunk type expected 

90. List filename expected 

91. List file already specified 

92. Linker format restriction 

93. Assembly interupted by user 


You pressed Control-C! 


94. Assembly failed 


A FAIL directive was issued in the assembly. 


95. Bad size, long expected 


(warning) 


96. Operand too large, byte expected 


(warning) 


97. Not allowed in BSS section. 


No code can be generated, only storage space (DS and DC directives) 

98. Bad Copper instruction 

99. Forward referenced Short Branch converted 
to NOP. 


And many many more... 
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